.TH std::mdspan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::mdspan \- std::mdspan

.SH Synopsis
   Defined in header <mdspan>
   template<

       class T,
       class Extents,                                   (since C++23)
       class LayoutPolicy = std::layout_right,
       class AccessorPolicy = std::default_accessor<T>

   > class mdspan;

   std::mdspan is a view into a contiguous sequence of objects that reinterprets it as
   a multidimensional array.

   Each specialization MDS of mdspan models copyable and satisfies:

     * std::is_nothrow_move_constructible_v<MDS> is true,
     * std::is_nothrow_move_assignable_v<MDS> is true, and
     * std::is_nothrow_swappable_v<MDS> is true.

   A specialization of mdspan is a TriviallyCopyable type if its accessor_type,
   mapping_type and data_handle_type are TriviallyCopyable types.

.SH Template parameters

   T              - element type; a complete object type that is neither an abstract
                    class type nor an array type.
   Extents        - specifies number of dimensions, their sizes, and which are known at
                    compile time. Must be a specialization of std::extents.
   LayoutPolicy   - specifies how to convert multidimensional index to underlying 1D
                    index (column-major 3D array, symmetric triangular 2D matrix, etc).
                    specifies how to convert underlying 1D index to a reference to T.
   AccessorPolicy - Must satisfy the constraint that std::is_same_v<T, typename
                    AccessorPolicy::element_type> is true.

    This section is incomplete
    Reason: add the requirement of layout policy and accessor policy.

.SH Member types

   Member type      Definition
   extents_type     Extents
   layout_type      LayoutPolicy
   accessor_type    AccessorPolicy
   mapping_type     LayoutPolicy::mapping<Extents>
   element_type     T
   value_type       std::remove_cv_t<T>
   index_type       Extents::index_type
   size_type        Extents::size_type
   rank_type        Extents::rank_type
   data_handle_type AccessorPolicy::data_handle_type
   reference        AccessorPolicy::reference

.SH Member objects

   Member name    Definition
   acc_ (private) The accessor of type accessor_type
                  (exposition-only member object*)
   map_ (private) The layout mapping of type mapping_type
                  (exposition-only member object*)
   ptr_ (private) The underlying data handle of type data_handle_type
                  (exposition-only member object*)

.SH Member functions

   constructor          constructs an mdspan
                        \fI(public member function)\fP
   operator=            assigns an mdspan
                        \fI(public member function)\fP
.SH Element access
   operator[]           accesses an element at the specified multidimensional index
                        \fI(public member function)\fP
.SH Observers
   size                 returns the size of the multidimensional index space
                        \fI(public member function)\fP
   empty                checks if the size of the index space is zero
                        \fI(public member function)\fP
   stride               obtains the stride along the specified dimension
                        \fI(public member function)\fP
   extents              obtains the extents object
                        \fI(public member function)\fP
   data_handle          obtains the pointer to the underlying 1D sequence
                        \fI(public member function)\fP
   mapping              obtains the mapping object
                        \fI(public member function)\fP
   accessor             obtains the accessor policy object
                        \fI(public member function)\fP
                        determines if this mdspan's mapping is unique (every
   is_unique            combination of indices maps to a different underlying element)
                        \fI(public member function)\fP
                        determines if this mdspan's mapping is exhaustive (every
   is_exhaustive        underlying element can be accessed with some combination of
                        indices)
                        \fI(public member function)\fP
                        determines if this mdspan's mapping is strided (in each
   is_strided           dimension, incrementing an index jumps over the same number of
                        underlying elements every time)
                        \fI(public member function)\fP
   is_always_unique     determines if this mdspan's layout mapping is always unique
   \fB[static]\fP             \fI(public static member function)\fP
   is_always_exhaustive determines if this mdspan's layout mapping is always exhaustive
   \fB[static]\fP             \fI(public static member function)\fP
   is_always_strided    determines if this mdspan's layout mapping is always strided
   \fB[static]\fP             \fI(public static member function)\fP

.SH Non-member functions

   std::swap(std::mdspan) specializes the std::swap algorithm for mdspan
   (C++23)                \fI(function template)\fP
         Subviews
   submdspan_extents      creates new extents from the existing extents and slice
   (C++26)                specifiers
                          \fI(function template)\fP
   submdspan              returns a view of a subset of an existing mdspan
   (C++26)                \fI(function template)\fP

   Helper types and templates

   extents                  a descriptor of a multidimensional index space of some rank
   (C++23)                  \fI(class template)\fP
   dextents                 convenience alias template for an all-dynamic std::extents
   (C++23)                  (alias template)
   layout_right             row-major multidimensional array layout mapping policy;
   (C++23)                  rightmost extent has stride 1
                            \fI(class)\fP
   layout_left              column-major multidimensional array layout mapping policy;
   (C++23)                  leftmost extent has stride 1
                            \fI(class)\fP
   layout_stride            a layout mapping policy with user-defined strides
   (C++23)                  \fI(class)\fP
   default_accessor         a type for indexed access to elements of mdspan
   (C++23)                  \fI(class template)\fP
         Subviews helpers
   full_extent              a slice specifier tag describing full range of indices in
   full_extent_t            the specified extent
   (C++26)                  (tag)
   strided_slice            a slice specifier representing a set of regularly spaced
   (C++26)                  indices as indicated by an offset, an extent, and a stride
                            \fI(class template)\fP
   submdspan_mapping_result a return type of the overloads of submdspan_mapping
   (C++26)                  \fI(class template)\fP

   Deduction guides

.SH Notes

   Feature-test macro   Value    Std      Feature
   __cpp_lib_mdspan    202207L (C++23) std::mdspan
   __cpp_lib_submdspan 202306L (C++26) std::submdspan

.SH Example

   Can be previewed on Compiler Explorer.


// Run this code

 #include <cstddef>
 #include <mdspan>
 #include <print>
 #include <vector>

 int main()
 {
     std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};

     // View data as contiguous memory representing 2 rows of 6 ints each
     auto ms2 = std::mdspan(v.data(), 2, 6);
     // View the same data as a 3D array 2 x 3 x 2
     auto ms3 = std::mdspan(v.data(), 2, 3, 2);

     // Write data using 2D view
     for (std::size_t i = 0; i != ms2.extent(0); i++)
         for (std::size_t j = 0; j != ms2.extent(1); j++)
             ms2[i, j] = i * 1000 + j;

     // Read back using 3D view
     for (std::size_t i = 0; i != ms3.extent(0); i++)
     {
         std::println("slice @ i = {}", i);
         for (std::size_t j = 0; j != ms3.extent(1); j++)
         {
             for (std::size_t k = 0; k != ms3.extent(2); k++)
                 std::print("{} ", ms3[i, j, k]);
             std::println("");
         }
     }
 }

.SH Output:

 slice @ i = 0
 0 1
 2 3
 4 5
 slice @ i = 1
 1000 1001
 1002 1003
 1004 1005

.SH See also

   span     a non-owning view over a contiguous sequence of objects
   (C++20)  \fI(class template)\fP
   valarray numeric arrays, array masks and array slices
            \fI(class template)\fP

.SH Category:
     * Todo with reason
